home *** CD-ROM | disk | FTP | other *** search
/ PC Media 4 / PC MEDIA CD04.iso / share / prog / filtr21 / filter21.doc < prev   
Encoding:
Text File  |  1994-06-14  |  8.3 KB  |  201 lines
  1. "filter", v. 2.1    Latest mod: 12:30 Jun 8 1994
  2.  A `grep'-like text searcher for multiple simultaneous keyword tests
  3.  
  4. Copyright 1994 by Joel Polowin, Department of Chemistry, Queen's University, 
  5. Kingston, Ontario, Canada.  Permission granted for free use and distribution;
  6. I want credit/blame for writing it.  E-mail: polowin@silicon.chem.queensu.ca,
  7. polowinj@qucdn.queensu.ca, Joel.Polowin@p4.f107.n249.z1.fidonet.org .
  8.  
  9. If you see something wrong with it or it fails to work, PLEASE let me know!
  10.  
  11. Syntax: filter [filename] [filename ...] string [string ...]
  12.     
  13.     where each string (default max. of 2000) is a term to be searched for
  14.     in lines (default max. 600 chars) in file(s) `filename', prefixed by one 
  15.     of the following characters:
  16.  
  17.        +  to show lines which contain string
  18.        -  to show lines which do not contain string
  19.        =  to show lines which contain string, case sensitive
  20.        _  (underscore) to show lines which do not contain string,
  21.            case sensitive
  22.  
  23. A string as above may be further prefixed with the letter 'o' to print the 
  24. line if the current OR the preceding condition is true.
  25.  
  26. A string including blanks and the prefix may be enclosed in double quotes
  27. on most systems.  Your operating system may have other ways of dealing
  28. with special characters.
  29.  
  30. "filter" determines the first string which is a search term instead of a
  31. file name by its beginning with one of the characters `+-=_'.  For files
  32. whose names begin with one of these characters, see below.  Otherwise, the
  33. first search term must begin with one of these, as that first term cannot
  34. be `or'-linked to a preceding term.
  35.  
  36. For strings that begin with `$', `&', or `^' (usually names of files of search
  37. terms), see below.
  38.  
  39. Examples:  
  40.  
  41. filter * +hawk +handsaw o+hound
  42.  
  43.    searches all files in the current directory and prints lines that
  44.    contain the string `hawk' and at least one of `handsaw' or `hound'.
  45.    This assumes that the operating system and compiler accept wild-carded
  46.    file names; else "filter" will be looking for a file named `*'.  For
  47.    DOS, one would use `*.*'.
  48.  
  49. filter armorial =Vert +argent -gules _Or -azure -purpur +foil > tempfile.txt
  50.      
  51.    searches the file `armorial' for lines that contain the string `Vert'
  52.    (case-sensitive) and `argent' (upper or lower case) but not `gules'
  53.    (upper or lower case) and not `Or' (case-sensitive) and not `azure'
  54.    or `purpur' (upper or lower case) and DO contain `foil' (upper or
  55.    lower case); the resulting lines are saved in file `tempfile.txt'.
  56.      
  57. type temp1.txt | filter +aardvark "o+winged pig" o+wombat "_|B|"
  58.  
  59.    The file `temp1.txt' is fed through the "filter" program, which passes
  60.    lines that contain `aardvark' (upper or lower case) or the string
  61.    `winged pig' or `wombat' (upper or lower case) and do NOT contain
  62.    `|B|'.  The result is printed on the screen.  Note use of quotation
  63.    marks in the command line to include the space in `winged pig' and the
  64.    special character `|' in `|B|'.
  65.  
  66. ----------
  67. File names beginning with one of `+-=_'
  68.  
  69. If you absolutely MUST use text file names that begin with one of these
  70. characters, use the character twice when specifying the file name to
  71. "filter".  Thus, the file name `-stdev.c' would be written `--stdev.c';
  72. `++junk.c' would be written `++++junk.c'.
  73.  
  74. What "filter" does is to go through each term in the command line and
  75. count the number of identical flag characters beginning each; that number
  76. is reduced by half, rounded down.  An even number specifies a text file name;
  77. an odd number designates a search term.  `+junk' has one flag character,
  78. is not changed (shortened by 1/2 -> 0 characters), and is a search term:
  79. print lines containing `junk'.  `++junk' has two flag characters, is 
  80. shortened to `+junk', and is read as a text file name.  `+++junk' is shortened 
  81. to `++junk', and is a search term: print lines containing the string `+junk'.
  82. `+=junk' has one flag character and is a search term: print lines containing
  83. the string `=junk'.
  84.  
  85. This means that wild-carded file names that match files whose names begin
  86. with one of `+-=_' will cause trouble.  I'm sorry; the telepathic monitors
  87. of most computer systems are not software-addressable.  A compulsive urge
  88. to use files whose names begin with punctuation or mathematical symbols 
  89. can now be treated successfully in a majority of cases.
  90.  
  91. Search terms specified in files (see below) are not themselves in the
  92. command line, and if they begin with one of `+-=_' those characters should
  93. not be doubled.  Search-term file expansion takes place after "filter"
  94. determines which command-line strings are file names.
  95.  
  96. ----------
  97. `$',`&', and `^' usually flag search-term file names.
  98.  
  99. A string which begins with `$', `&', or `^' will be expanded as the name of a 
  100. file containing a list of search terms.  For example, the string +$critters
  101. tells "filter" to look for a file `critters'; lines from that file are taken
  102. as search terms.
  103.  
  104. If the file name is specified with `^', terms INCLUDING `+-=_' prefixes are
  105. read from the file.  The string specifying the file name is replaced in the
  106. command line by the list of terms read from the file; the original prefix
  107. is ignored.  "filter" does not add `+-=_' prefixes to the terms.
  108.  
  109. If the file name is specified with `$' or `&', "filter" adds the prefix to 
  110. each term, depending on which of `$&' is used and which of `+-=_' precedes it.
  111. With `$', `+' and `=' give or-linked terms, so that text file lines will be
  112. printed if any search-term file line is matched; `-' and `_' are not
  113. or-linked, so that text file lines are printed only if no search-term file
  114. line is matched.  With `&', `+' and `=' are not or-linked, so that ALL
  115. search-term lines must be matched to print a text line; while `-' and `_'
  116. ARE or-linked, so that any search-term line NOT matched will allow text-line
  117. printing.
  118.  
  119. To search for actual text strings beginning with `$', `&', or `^', double the
  120. flag characters.  Thus, to search for the string `$100', use the search
  121. string `+$$100'.  To expand file names beginning with those characters,
  122. use three of them: search-term file `$&junk' would be specified with something
  123. like `-$$$&junk'.  In general, when a search term begins with a flag
  124. character, double each flag character of that kind beginning the term, and
  125. if the term is a file name, add an extra flag character.
  126.  
  127. Search-term files may contain file names, which will be expanded in turn.
  128. For this reason, initial `$', `&', and `^' characters must be doubled even in
  129. nested search-term files.
  130.  
  131. Note that the or-linking logic can get seriously messed up when terms
  132. beginning with `-' or `_' are expanded carelessly, as "filter" has no good
  133. sense of logical precedence.  If file `human' contains `man' and `woman',
  134. then `o-$human' would expand as `o-man -woman'.
  135.  
  136. Examples:
  137.  
  138. filter armorial +$animal o+$vegetable _^mineral
  139.  
  140.    If file `animal' reads
  141.    $human
  142.    reptile
  143.    amphibian
  144.  
  145.    and file `human' reads
  146.    man
  147.    woman
  148.    
  149.    and file `vegetable' reads
  150.    tree
  151.    grain
  152.  
  153.    and file `mineral' reads
  154.    +rock
  155.    -dirt
  156.  
  157.    then the above will be expanded to:
  158.    
  159.    filter armorial +man o+woman o+reptile o+amphibian o+tree o+grain +rock
  160.      -dirt
  161.  
  162. filter armorial +$&beastie +&&&doggie -$dragon
  163.  
  164.    If file `&beastie' reads
  165.    unicorn
  166.    $dragon
  167.    manticore
  168.  
  169.    and file `&doggie' reads
  170.    terrier
  171.    hound
  172.    $$paniel
  173.  
  174.    and file `dragon' reads
  175.    wyvern
  176.    dragon
  177.    lizard
  178.  
  179.    then the above will be expanded to
  180.  
  181.    filter armorial +unicorn o+wyvern o+dragon o+lizard o+manticore +terrier 
  182.      +hound +$$paniel -wyvern -dragon -lizard
  183.  
  184.    which will print lines from file `armorial' that contain: 
  185.      any of: `unicorn', `wyvern', `dragon', `lizard', `manticore'; and
  186.      ALL of: `terrier', `hound', `$paniel'; and
  187.      none of: `wyvern', `dragon', `lizard'.
  188.  
  189. Revision history:
  190.  
  191. Version 1.0 September 1992.
  192.  
  193. 1.1 Sep '92 fixed minor bugs
  194. 1.2 Sep '92 added 'or'-linking to keywords
  195. 1.4 Oct '92 fixed a minor error in string lengths, added size DEFINEs
  196. 1.5 Jan '94 increased string lengths, fixed a Stupid Newbie Error re:
  197.         assumption that *argv[] was writable
  198. 2.0 Feb '94 added search-term file expansion and multiple text file
  199.         capability, including wildcards when system permits
  200. 2.1 Jun '94 added null-prefix search-term files and term-file `rewind'
  201.